/** 
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fpdfedit.h
 * @brief	Header file for the PDF Edit module.
 * @details	The PDF Edit module offers methods to do some operations on editing PDF.
 *			<br>
 *			Following the specification of PDF, users can edit the PDF page object such as geting, modifying, setting and deleting.
 *			Now this module only support the image object.
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling Edit module explicitly. 
 */

/** 
 * @addtogroup FGSPDFEDIT PDF Edit
 * @brief Methods in this module are included in fpdfedit.h
 */

/** @{*/

#ifndef __FGSPDFEDIT__
#define __FGSPDFEDIT__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif
    
/**
 * @brief Create a new PDF document.
 *
 * @return	Reference to a PDF document.
 *
 */
FGSPDFDocumentRef FGSPDFDocCreateNew();

/**
 * @brief Set the meta data into a PDF document.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] key			The string specifying the key which is set.
 * @param[in] text			The string specifying the value which is set.
 *
 * @return	::kFGSErrorSuccess means setting the meta text successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocSetMetaText(FGSPDFDocumentRef document, CFStringRef key, CFStringRef text);

/**
 * @brief Create a new page.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] index			The index specifying the position of the created page. 
 *
 * @return	Reference to a PDF page.
 *
 */
FGSPDFPageRef FGSPDFPageCreateNewPage(FGSPDFDocumentRef document, SInt32 index);

/**
 * @brief	Change page index.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] newIndex		The new page index to set.
 *
 * @return	The final page index.
 *
 */
SInt32 FGSPDFPageSetPageIndex(FGSPDFPageRef page, SInt32 newIndex);

/**
 * @brief Delete a page from document.
 *
 * @param[in] page			Reference to a PDF page.
 *
 * @return	::kFGSErrorSuccess means setting the meta text successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageDeletePage(FGSPDFPageRef page);

/**
 * @brief Get the reference of the page objects on the specify page.
 *
 * @param[in] page			Reference to a PDF page.	
 *
 * @return Reference to a page objects.
 */
FGSPDFPageObjectsRef FGSPDFPageGetObjects(FGSPDFPageRef page);
    
/**
 * @brief Set the size of a page.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] width			The width of a page which is set.
 * @param[in] height		The height of a page which is set.
 *
 * @return	::kFGSErrorSuccess means setting the meta text successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageSetPageSize(FGSPDFPageRef page, Float32 width, Float32 height);

/**
 * @brief	Add a mark string on the special page. Only English text string is supported now.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] page			Reference to a PDF page.
 * @param[in] x				The value of the X position in the PDF page coordination system.
 * @param[in] y				The value of the Y position in the PDF page coordination system.
 * @param[in] fontsize		The font size which is to be used to write the string.<br>
 * @param[in] string		The text string which is to be written on the page.<br>
 *
 * @return	::kFGSErrorSuccess means setting the meta text successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageAddPageModifyMark(FGSPDFDocumentRef document, FGSPDFPageRef page, Float32 x, Float32 y, SInt32 fontsize, CFStringRef string);

/**
 * @brief Generate the content of a pdf page.
 *
 * @param[in] page			Reference to a PDF page.
 *
 * @return	::kFGSErrorSuccess means setting the meta text successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageGenerateContent(FGSPDFPageRef page);

/**
* @brief Set a page rectangle, in points (1 point equals 1/72 inch).
*
* @param[in] page			Reference to a PDF page.
* @param[in] iRect			The index values for getting boxes refers to definitions of <b>FGSPDFRectType</b> <br>
*							except ::kFGSPDFRectPage and ::kFGSPDFRectBounding.
* @param[in] pagerect		The page rectangle which to set.
*
* @return ::kFGSErrorSuccess means get the size successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
* @note   After using this method, the content in the page will be changed, but not loaded.
*		  You must call the ::FGSPDFPageLoadPage to reload the page.
*/
FGSErrorRet FGSPDFPageSetRectangle(FGSPDFPageRef page, SInt32 iRect, CGRect *rect);

/**
* @brief Set page rotation. One of following values will be set: 0(0), 1(90), 2(180), 3(270).
*
* @param[in] page			Reference to a PDF page.
* @param[in] rotate			The value of the PDF page rotation.
*
* @return ::kFGSErrorSuccess means get the size successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
* @note	The PDF page rotation is rotated clockwise.
*		After using this method, the content in this page will be changed, but not loaded.
*		You must call the ::FGSPDFPageLoadPage to reload the page.
*/
FGSErrorRet FGSPDFPageSetRotation(FGSPDFPageRef page, SInt32 rotate);

/**
 * @brief	Insert the pageObj to a PageObjects.
 *
 * @param[in] pageObjs	Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] pageObj	Reference to a page object to be inserted.
 * @param[in] index		Zero-based index for a page object which is the new position to move after. If <br>
 *						index >= count of page objects returned by ::FGSPDFPageObjectsCountObjects, <br>
 *						the page object will move to the top. If index < 0, the page object will move to the bottom.<br>
 *
 * @return	The new index of the page object.
 */
SInt32 FGSPDFPageObjectsInsertObject(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectRef pageObj, SInt32 index);

/**
 * @brief	Remove the pageObj from a PageObjects.
 *
 * @param[in] pageObjs	Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] index		Zero-based index for a page object.
 *
 * @return	::kFGSErrorSuccess means get the size successfully.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFPageObjectsDeleteObject(FGSPDFPageObjectsRef pageObjs, SInt32 index);

/**
 * @brief	Get the count of a PageObjects.
 *
 * @param[in] pageObjs	Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 *
 * @return	The count of a PageObjects.
 */
SInt32 FGSPDFPageObjectsCountObjects(FGSPDFPageObjectsRef pageObjs);

/**
 * @brief	Get the specific page object in a PageObjects.
 *
 * @param[in] pageObjs	Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] index		Zero-based index for a page object.
 *
 * @return	The specific page object.
 */
FGSPDFPageObjectRef FGSPDFPageObjectsGetObject(FGSPDFPageObjectsRef pageObjs, SInt32 index);

/**
 * @brief	Get the index of the specific page object in a PageObjects.
 *
 * @param[in] pageObjs	Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] pageObj	Reference to a page object.
 *
 * @return	The zero-based index of the specific page object.
 */
SInt32 FGSPDFPageObjectsGetObjectIndex(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the position of the specific page object on the page.
 *
 * @param[in] pageObjs		Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] pageObj		Reference to a page object.		
 *
 * @return Reference to a <b>::FGSPDFPageObjectPosRef</b> object that receives the position of the page object on the page.
 */
FGSPDFPageObjectPosRef FGSPDFPageObjectsGetObjectPos(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the head position of the specific page objects on the page.
 *
 * @param[in] pageObjs			Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 *
 * @return Reference to a <b>::FGSPDFPageObjectPosRef</b> object that receives the head position of the page objects on the page.
 */
FGSPDFPageObjectPosRef FGSPDFPageObjectsGetFirstObjectPos(FGSPDFPageObjectsRef pageObjs);

/**
 * @brief Get the trail position of the specific page objects on the page.
 *
 * @param[in] pageObjs			Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 *
 * @return Reference to a <b>::FGSPDFPageObjectPosRef</b> object that receives the trail position of the page objects on the page.
 */
FGSPDFPageObjectPosRef FGSPDFPageObjectsGetLastObjectPos(FGSPDFPageObjectsRef pageObjs);

/**
 * @brief Get the page object by specific position in the page objects on the page, and the pos move to next position.
 *
 * @param[in] pageObjs			Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in, out] pos			Pointer to a <b>::FGSPDFPageObjectPosRef</b> object that specifies the position <br>
 *								and receives the next position in the page objects on the page.
 *
 * @return Reference to a page object according to the specific position on the page.
 */
FGSPDFPageObjectRef FGSPDFPageObjectsGetNextObject(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectPosRef* pos);

/**
 * @brief Get the page object by specific position in the page objects on the page, and the pos move to previous position.
 *
 * @param[in] pageObjs			Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in, out] pos			Pointer to a <b>::FGSPDFPageObjectPosRef</b> object that specifies the position <br>
 *								and receives the previous position in the page objects on the page.
 *
 * @return Reference to a page object according to the specific position on the page.
 */
FGSPDFPageObjectRef FGSPDFPageObjectsGetPrevObject(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectPosRef* pos);

/**
 * @brief Get the page object by specific position in the page objects on the page.
 *
 * @param[in] pageObjs		Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] pos			Reference to a <b>::FGSPDFPageObjectPosRef</b> object specifying the position in the page objects on the page.
 *
 * @return Reference to a page object according to the specific position on the page.
 */
FGSPDFPageObjectRef FGSPDFPageObjectsGetObjectAt(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectPosRef pos);

/**
 * @brief Delete the page object by specific position in the page objects on the page.
 *
 * @param[in] pageObjs		Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] pos			Reference to a <b>::FGSPDFPageObjectPosRef</b> object specifying the position in the page objects on the page.
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjectsDeleteObjectAt(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectPosRef pos);

/**
 * @brief Insert the page object by specific successor position in the page objects on the page.
 *
 * @param[in] pageObjs			Reference to a <b>::FGSPDFPageObjectsRef</b> object.
 * @param[in] posInsertAfter	Reference to a <b>::FGSPDFPageObjectPosRef</b> object specifying the specific successor position in the page objects on the page.
 * @param[in] pageObj			Reference to a page object to be inserted. 		
 *
 * @return Reference to a a <b>::FGSPDFPageObjectPosRef</b> object that receices the inserted position.
 */
FGSPDFPageObjectPosRef FGSPDFPageObjectsInsertObjectAfter(FGSPDFPageObjectsRef pageObjs, FGSPDFPageObjectPosRef posInsertAfter, FGSPDFPageObjectRef pageObj);

/**
 * @brief Transform the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] matrix		The transform matrix.		
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjTransform(FGSPDFPageObjectRef pageObj, CGAffineTransform matrix);
    
/**
 * @brief Clone the page object.
 *
 * @param[in] pageObj		Reference to a page object.	
 *
 * @return Reference to a <b>::FGSPDFPageObjectRef</b> object that receices the result of cloned page object.
 */
FGSPDFPageObjectRef FGSPDFPageObjClone(FGSPDFPageObjectRef pageObj);

/**
 * @brief Release the page object.
 *
 * @param[in] pageObj		Reference to a page object.	
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjRelease(FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the type of the page object.
 *
 * @param[in] pageObj		Reference to a page object.	
 *
 * @return The type of the page object. For more definitions please see macro definitions <b>FGSPDFPageObjType</b>.
 */
FGSPDFPageObjType FGSPDFPageObjGetType(FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the bounding box of the page object.
 *
 * @param[in] pageObj		Reference to a page object.	
 *
 * @return  A CGRect object receives the bounding box of the page object.
 */
CGRect FGSPDFPageObjGetBBox(FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the count of the page object clips.
 *
 * @param[in] pageObj		Reference to a page object.	
 *
 * @return  The count of the page object clips.
 */
SInt32 FGSPDFPageObjCountClips(FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the specific clip of the page object clip regions.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] index		The specific index.
 *
 * @return  Reference to a <b>::FGSPDFPathRef</b> object that receives the specified clip region.
 */
FGSPDFPathRef FGSPDFPageObjGetClip(FGSPDFPageObjectRef pageObj, int index);

/**
 * @brief Add a clip region to the page object clip regions.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] path		Reference to a <b>::FGSPDFPathRef</b> object.
 * @param[in] type		The type of the clip region.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjAddClip(FGSPDFPageObjectRef pageObj, FGSPDFPathRef path, SInt32 type);

/**
 * @brief Add a path clip region to the page object clip regions.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] path		Reference to a <b>::FGSPDFPathRef</b> object.
 * @param[in] type		The type of the clip region.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjAppendPathToClip(FGSPDFPageObjectRef pageObj, FGSPDFPathRef path, SInt32 type);

/**
 * @brief Remove the specific clip region from the page object clip regions.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] index		The index of the clip region.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjRemoveClip(FGSPDFPageObjectRef pageObj, SInt32 index);

/**
 * @brief Get the fill color of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The fill color of the page object.
 */
UInt32 FGSPDFPageObjGetFillColor(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the fill color of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] fillColor		The fill color of the page object.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetFillColor(FGSPDFPageObjectRef pageObj, UInt32 fillColor);

/**
 * @brief Get the stroke color of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The stroke color of the page object.
 */
UInt32 FGSPDFPageObjGetStrokeColor(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the stroke color of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] strokeColor	The stroke color.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetStrokeColor(FGSPDFPageObjectRef pageObj, UInt32 strokeColor);

/**
 * @brief Get the Line width of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The Line width of the page object.
 */
Float32 FGSPDFPageObjGetLineWidth(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the Line width of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] lineWidth		The Line width.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetLineWidth(FGSPDFPageObjectRef pageObj, Float32 lineWidth);

/**
 * @brief Get the Line capStyle of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The Line capStyle of the page object.
 */
FGSPDFLineCapStyle FGSPDFPageObjGetLineCapStyle(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the Line CapStyle of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] lineCapStyle	The Line CapStyle.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetLineCapStyle(FGSPDFPageObjectRef pageObj, FGSPDFLineCapStyle lineCapStyle);

/**
 * @brief Get the Line JoinStyle of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The Line JoinStyle of the page object.
 */
FGSPDFLineJoinStyle FGSPDFPageObjGetLineJoinStyle(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the Line JoinStyle of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] lineJoinStyle	The Line JoinStyle.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetLineJoinStyle(FGSPDFPageObjectRef pageObj, FGSPDFLineJoinStyle lineJoinStyle);

/**
 * @brief Get the MiterLimit of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The MiterLimit of the page object.
 */
Float32 FGSPDFPageObjGetMiterLimit(FGSPDFPageObjectRef pageObj);

/**
 * @brief Set the MiterLimit of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] miterLimit	The MiterLimit of the page object.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFPageObjSetMiterLimit(FGSPDFPageObjectRef pageObj, Float32 miterLimit);

/**
 * @brief Get the dash array of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in, out] array	The Floating-point array to receive the dash array.
 * @param[out] count		The Floating-point count of the array.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjGetDashArray(FGSPDFPageObjectRef pageObj, Float32 array[], SInt32 *count);

/**
 * @brief Set the dash array of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] array		The Floating-point array to store the dash array.
 * @param[in] count		The Floating-point count of the array.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetDashArray(FGSPDFPageObjectRef pageObj, Float32 array[], SInt32 count);

/**
 * @brief Get the dash phase of the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The dash phase of the page object.
 */
Float32 FGSPDFPageObjGetDashPhase(FGSPDFPageObjectRef pageObj);
    
/**
 * @brief Set the dash phase of the page object.
 *
 * @param[in] pageObj		Reference to a page object.
 * @param[in] phaseValue	The dash phase of the page object.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjSetDashPhase(FGSPDFPageObjectRef pageObj, Float32 phaseValue);

/**
 * @brief Get the count of ContentMark in the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 *
 * @return  The count of ContentMark in the page object.
 */
SInt32 FGSPDFPageObjCountContentMarks(FGSPDFPageObjectRef pageObj);

/**
 * @brief Get the ContentMark name by the specific index in the page object.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] index		The specific index.
 *
 * @return  The ContentMark name specified by the index value.
 */
CFStringRef FGSPDFPageObjCopyContentMarkNameByIndex(FGSPDFPageObjectRef pageObj, SInt32 index);

/**
  * @brief Check if there is a content with a special name in the pageObject.
  * 
  * @param[in] pageObj	Reference to a page object.
  * @param[in] tagName	The name string of the content mark.
  *
  * @return The flag value whether has the content mark.
  */
Boolean FGSPDFPageObjHasContentMark(FGSPDFPageObjectRef pageObj, CFStringRef tagName);

/**
 * @brief brief Add a content mark into a pageObjcet.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] tagName	The name string of the content mark.
 *
 * @return  ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjAddContentMark(FGSPDFPageObjectRef pageObj, CFStringRef tagName);

/**
 * @brief Delete a content mark from a pageObject.
 *
 * @param[in] pageObj	Reference to a page object.
 * @param[in] tagName	The name string of the content mark.
 *
 * @return ::kFGSErrorSuccess means exporting successfully.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageObjDelContentMark(FGSPDFPageObjectRef pageObj, CFStringRef tagName);

/**
 * @brief Create a new text Object.
 * 
 * @param[in] textObject	Reference to a text object.
 * 
 * @return ::kFGSErrorSuccess means exporting successfully.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSPDFPageObjectRef FGSPDFPageObjCreateTextObject();

/**
* @brief Create a new text object.
*
* @param[in] text			A string that stores the text for the text object.
* @param[in] nwSize			The length of the string.
* @param[in] font			Reference to a font object returned by ::FGSPDFTextObjGetFont, ::FGSPDFFontAddStandardFont.		
*
* @return Reference to the text object or NULL if an error occurs.
*/
FGSPDFPageObjectRef FGSPDFPageObjCreateTextObjectEx(CFStringRef text, SInt32 nwSize, FGSPDFFontRef font);

/**
* @brief Get the font reference of a text object.
*
* @param[in] pageObj		Reference to a text object.			
*
* @return Reference to a font object.
*/
FGSPDFFontRef FGSPDFTextObjGetFont(FGSPDFPageObjectRef pageObj);

/**
* @brief Set the font of a text object.
*
* @param[in] pageObj		Reference to a text object returned by ::FGSPDFPageObjCreateTextObject 
*							or ::FGSPDFPageObjCreateTextObjectEx.
* @param[in] font			Reference to a font object returned by ::FGSPDFTextObjGetFont, ::FGSPDFFontAddStandardFont.      
* @param[in] font_size		The size of the font.  
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFTextObjSetFont(FGSPDFPageObjectRef pageObj, FGSPDFFontRef font, Float32 font_size);

/**
* @brief Get the font size of a text object.
*
* @param[in] pageObj		Reference to a text object.	
*
* @return The value of the font size.
*/
Float32 FGSPDFTextObjGetFontSize(FGSPDFPageObjectRef pageObj);

/**
* @brief Get the text object matrix.
*
* @param[in] pageObj		Reference to a text object.					
*
* @return The text object matrix.
*/
CGAffineTransform FGSPDFTextObjGetMatrix(FGSPDFPageObjectRef pageObj);

/**
* @brief Get the number of characters in a text object.
*
* @param[in] pageObj		Reference to a text object.
*
* @return The character count of the text object.
*/
SInt32 FGSPDFTextObjCountChars(FGSPDFPageObjectRef pageObj);

/**
* @brief Get the unicode of a specified character in a text object.
*
* @param[in] pageObj		Reference to a text object returned by ::FGSPDFPageObjCreateTextObject 
*							or ::FGSPDFPageObjCreateTextObjectEx.
* @param[in] index			The index of the character to get the unicode value of. 
*
* @return The unicode value of the specified character.
*/
SInt32 FGSPDFTextObjGetUnicode(FGSPDFPageObjectRef pageObj, SInt32 index);

/**
* @brief Set the unicode of a specified character in a text object.
*
* @param[in] pageObj		Reference to a text object.	
* @param[in] index			The index of the character to set unicode value of.
* @param[in] unicode		The unicode value.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFTextObjSetUnicode(FGSPDFPageObjectRef pageObj, SInt32 index, SInt32 unicode);

/**
* @brief Calculate the physical offset from the start to the specified character. 
*
* @param[in] pageObj		Reference to a text object.	
* @param[in] index			The index of the character to calculate the offset of.
*
* @return The offset value.
*/
Float32 FGSPDFTextObjGetOffset(FGSPDFPageObjectRef pageObj, SInt32 index);

/**
* @brief Get the text rendering mode.
*
* @param[in] pageObj	Reference to the text object.
*
* @return The value of the text rendering mode refers to definitions of <b>FGSPDFTextMode</b>.
*/
FGSPDFTextMode FGSPDFTextObjGetTextMode(FGSPDFPageObjectRef pageObj);

/**
* @brief Set the text rendering mode.
*
* @param[in] pageObj	Reference to a text object.	
* @param[in] textMode	The text mode refers to definitions of <b>FGSPDFTextMode</b>.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFTextObjSetTextMode(FGSPDFPageObjectRef pageObj, FGSPDFTextMode textMode);

/**
* @brief Get the character spacing value of a text object.
*
* @param[in] pageObj	Reference to a text object.
*
* @return The character spacing value.
* @note The character spacing value is a number specified in unscaled text space units.
*/
Float32 FGSPDFTextObjGetCharSpace(FGSPDFPageObjectRef pageObj);

/**
* @brief Set the character spacing value of a text object.
*
* @param[in] pageObj	Reference to a text object.	
* @param[in] charSpace	The character spacing value. 	
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
* @note The character spacing value is a number specified in unscaled text space units. 
*/
FGSErrorRet FGSPDFTextObjSetCharSpace(FGSPDFPageObjectRef pageObj, Float32 charSpace);

/**
* @brief Get the word spacing value of a text object.
*
* @param[in] pageObj	Reference to a text object.	
*
* @return The word spacing value.
* @note The word spacing value is a number expressed in unscaled text space units.
*/
Float32 FGSPDFTextObjGetWordSpace(FGSPDFPageObjectRef pageObj);

/**
* @brief Set the word spacing value of a text object.
*
* @param[in] pageObj	Reference to a text object.	
* @param[in] wordSpace	The word spacing value.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFTextObjSetWordSpace(FGSPDFPageObjectRef pageObj, Float32 wordSpace);

/**
* @brief Insert a substring at the given index within the text object.
*
* @param[in] pageObj	Reference to a text object.
* @param[in] text		A substring to be inserted.
* @param[in] index		The index of the character before which the insertion will take place.
*
* @return The length of the modified string.
* @note   The index can be between 0 and the number of characters returned by ::FGSPDFTextObjCountChars.
*/
SInt32 FGSPDFTextObjInsertText(FGSPDFPageObjectRef pageObj, CFStringRef text, SInt32 index);

/**
* @brief Delete a character or characters in the text object.
*
* @param[in] pageObj	Reference to a text object.
* @param[in] index		The index of the first character to delete.
* @param[in] nCount		The number of characters to be removed.
*
* @return The character number of the changed text object.
* @note Call this member function to delete a character or characters from a string starting with the character at index. 
*		If nCount is longer than the string, the remainder of the string will be removed.
*/
SInt32 FGSPDFTextObjDeleteText(FGSPDFPageObjectRef pageObj, SInt32 index, SInt32 nCount);

/**
* @brief Find a substring inside a text object.
*
* @param[in] pageObj	Reference to a text object.
* @param[in] text		A string to search for.
* @param[in] nStart		The index of the character in the string to begin the search with, 
*						or 0 to start from the beginning.
*
* @return The zero-based index of the first character in this text object that matches the requested <br>
*								substring or characters; -1 if the substring or character is not found.
*/
SInt32 FGSPDFTextObjFindText(FGSPDFPageObjectRef pageObj, CFStringRef text, SInt32 nStart);

/**
* @brief Replace a character with another.
*
* @param[in] pageObj	Reference to a text object.
* @param[in] OldText	A string containing the character to be replaced by NewText.
* @param[in] NewText	A string containing the character replacing OldText.
*
* @return The number of characters of the changed text object. -1 if the text object isn't changed.
*/
FGSErrorRet FGSPDFTextObjReplaceText(FGSPDFPageObjectRef pageObj, CFStringRef OldText, CFStringRef NewText);

/**
* @brief Compare current text object characters with another string. 
*
* @param[in] pageObj	Reference to a text object.
* @param[in] text		A string used for comparison.	
*
* @return TRUE if the texts are identical, and FALSE if they are different.
*/
Boolean	FGSPDFTextObjCompareText(FGSPDFPageObjectRef pageObj, CFStringRef text);

/**
* @brief Create a new path Object.
*
* @return Reference to the path object.
*/
FGSPDFPageObjectRef FGSPDFPageObjCreatePathObject();

/**
* @brief Set the points in a path object.
*
* @param[in] path_object	Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] points			The pointer to point at an array of points.
* @param[in] flags			The pointer to point at an array of the path point types defined above.
* @param[in] count			The total number of points.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFPathObjSetPoints(FGSPDFPageObjectRef path_object, CGPoint points[], FGSPDFPathPointType flags[], SInt32 count);

/**
* @brief Insert a point to a path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] point				The coordinate of a point.
* @param[in] flag				The path point types defined above.
* @param[in] point_index		The index of the point.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFPathObjInsertPoint(FGSPDFPageObjectRef path_object, CGPoint point, FGSPDFPathPointType flag, SInt32 point_index);

/**
* @brief Remove a point in a path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] point_index		The index of the point.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFPathObjDeletePoint(FGSPDFPageObjectRef path_object, int point_index);

/**
* @brief Clear the points in a path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet FGSPDFPathObjClearPoints(FGSPDFPageObjectRef path_object);

/**
* @brief Get the number of points in a path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return The point count in a path object.
*/
SInt32 FGSPDFPathObjCountPoints(FGSPDFPageObjectRef path_object);

/**
* @brief Get the type of a special point.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] point_index		The index of the point.
*
* @return The path point type refers to definitions of <b>FGSPDFPathPointType</b>.
*/
FGSPDFPathPointType FGSPDFPathObjGetPointType(FGSPDFPageObjectRef path_object, SInt32 point_index);

/**
* @brief Get the X coordinate of a specific point.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] point_index		The index of the point.
*
* @return The value of the X coordinate of the point.
*/
Float32 FGSPDFPathObjGetPointX(FGSPDFPageObjectRef path_object, SInt32 point_index);

/**
* @brief Get the Y coordinate of a specific point.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] point_index		The index of the point.
* 
* @return The value of the Y coordinate of the point.
*/
Float32 FGSPDFPathObjGetPointY(FGSPDFPageObjectRef path_object, SInt32 point_index);

/**
* @brief Get the path in a path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return The path in the path object.
*/
FGSPDFPathRef FGSPDFPathObjGetPath(FGSPDFPageObjectRef path_object);

/**
* @brief Get the stroke mode of the path.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return The stroke mode, TRUE for stroking the line, FALSE for no stroking.
*/
Boolean FGSPDFPathObjGetStroke(FGSPDFPageObjectRef path_object);

/**
* @brief Get the fill mode of the path.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return The fill mode types defined above.
*/
FGSPDFFillModeType FGSPDFPathObjGetFillMode(FGSPDFPageObjectRef path_object);

/**
* @brief Set the fill and stroke mode of the path.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
* @param[in] fill_type			The fill mode. See definitions of <b>FGSPDFFillModeType</b>.
* @param[in] stroke				The stroke mode. TRUE for stroking the line, FALSE for no stroking.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
FGSErrorRet	FGSPDFPathObjSetFillStroke(FGSPDFPageObjectRef path_object, FGSPDFFillModeType fill_type, SInt32 stroke);

/**
* @brief Get the matrix of the path object.
*
* @param[in] path_object		Reference to a path object returned by ::FGSPDFPageObjCreatePathObject.
*
* @return The matrix of the path.
*/
CGAffineTransform FGSPDFPathObjGetMatrix(FGSPDFPageObjectRef path_object); 

/**
 * Create a new form object.
 *
 * @param[in]	document		Reference to a PDF document.
 *
 * @return The new form object.
 */
FGSPDFPageObjectRef FGSPDFFormObjCreateFormObj(FGSPDFDocumentRef document);

/**
* @brief Generate content of the form object.
*
* @param[in] form_object		Reference to a form object.
*
* @return ::kFGSErrorSuccess means exporting successfully.<br>
*		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
* @note	When the form object's information changes, the user must call the ::FGSPDFFormObjGenerateContent function.
*		Otherwise, the modified information will be lost.
*/
FGSErrorRet FGSPDFFormObjGenerateContent(FGSPDFPageObjectRef form_object);

/**
* @brief Get the matrix of the form object.
*
* @param[in] form_object		Reference to a form object.
*
* @return The matrix of the form object.
*/
CGAffineTransform FGSPDFFormObjGetMatrix(FGSPDFPageObjectRef form_object);

/**
 * @brief Gets the objects in the form object.
 *
 * @param[in] form_object		Reference to a form object.	
 *
 * @return The Reference to a page objects.
 */
FGSPDFPageObjectsRef FGSPDFFormObjGetObjects(FGSPDFPageObjectRef form_object);
    
/**
 * @brief Get count of all image objects in a page.
 *
 * @param[in] page			Reference to a PDF page.
 *
 * @return The count number of all image object in page.
 * @note Before call this function, page contents should be parsed. <br>
 *		 Refer to FGSPDFPageStartParsingPage and FGSPDFPageContinueParsingPage.
 */
SInt32 FGSPDFImageObjCountImageObjects(FGSPDFPageRef page);

/**
 * @brief Get an image object in a page.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] index			Zero-based index of image object in a page.
 *
 * @return Reference to a image object retrieved from page.
 * @note Before call this function, page contents should be parsed. <br>
 *		 Refer to ::FGSPDFPageStartParsingPage and ::FGSPDFPageContinueParsingPage.
 */
FGSPDFPageObjectRef FGSPDFImageObjGetImageObjectByIndex(FGSPDFPageRef page, SInt32 index);

/**
 * @brief Get a image object on a specified point.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] point			The value of position in the PDF page coordination system.
 * @param[in] tolerance		The tolerance value for image hit detection, in point units. This should not be a negative.
 *
 * @return The reference to the image object.
 */
FGSPDFPageObjectRef FGSPDFImageObjGetImageObjectAtPos(FGSPDFPageRef page, CGPoint point, Float32 tolerance);

/**
 * @brief Get DIB of a image object copy.
 *
 * @param[in] imageObj		Reference to an image object.
 *
 * @return Reference to the returned image object.
 * @note The Caller function should delete this CGImageRef object.
 */
CGImageRef FGSPDFImageObjCopyBitmap(FGSPDFPageObjectRef imageObj);

/**
 * @brief Create a image object.
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return Reference to the returned image object.
 */
FGSPDFPageObjectRef FGSPDFImageObjCreateImageObject(FGSPDFDocumentRef document);

/**
 * @brief Load a image file into a image object.
 *
 * @param[in] imageobj		Reference to an image object.
 * @param[in] fileread		Reference to a <b>::FGSFileStreamInRef</b> object to read a image file.
 *
 * @return ::kFGSErrorSuccess means load successfully.<br>
 *		   For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFImageObjLoadImageObject(FGSPDFPageObjectRef imageobj, FGSFileStreamInRef fileread);

/**
 * @brief Set a bitmap whose type is CGImage into a image object.
 *
 * @param[in] imageobj		Reference to an image object.
 * @param[in] bitmap		Reference to a CGImage object.
 *
 * @return	::kFGSErrorSuccess means set successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFImageObjSetBitmap(FGSPDFPageObjectRef imageobj, CGImageRef bitmap);

/**
 * @brief Get the matrix of a image object.
 *
 * @param[in] imageobj		Reference to a PDF page.
 *
 * @return A CGAffineTransform object to receive the returned data.
 */
CGAffineTransform FGSPDFImageObjGetMatrix(FGSPDFPageObjectRef imageobj);

/**
 * @brief Add the bookmark to the document.
 * @param[in] document		Reference to a PDF document.
 * @param[in] parent		The parent node.
 * @param[in] InsterAfter	The former node.
 * @param[in] titlename		A string specifying the bookmark name.
 *
 * @return The setting bookmark object, if successful. If failed, NULL is returned.
 */
FGSPDFBookmarkRef FGSPDFBookmarkAddBookmark(FGSPDFDocumentRef document, FGSPDFBookmarkRef parent, FGSPDFBookmarkRef InsterAfter, CFStringRef titlename);

/**
 * @brief Delete the bookmark object
 *
 * @param[in] document	Reference to a PDF document.
 * @param[in] bookmark	Reference to a bookmark.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFBookmarkDelBookmark(FGSPDFDocumentRef document, FGSPDFBookmarkRef bookmark);

/**
 * @brief Set the bookmark title.
 *
 * @param[in] bookmark		Reference to a bookmark.
 * @param[in] titlename		A string specifying the title name.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFBookmarkSetTitle(FGSPDFBookmarkRef bookmark, CFStringRef titlename);

/**
 * @brief Set the bookmark color. The color value such as (0xFF00FF).
 *
 * @param[in] bookmark	Reference to a bookmark.
 * @param[in] color		The color value to set.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFBookmarkSetColor(FGSPDFBookmarkRef bookmark, UInt32 color);

/**
 * @brief Set the bookmark font style(such as bold, italic and so on).
 *
 * @param[in] bookmark		Reference to a bookmark.
 * @param[in] Fontstyle		The font type refers to definitions of <b>FGSBookmarkFontStyle</b>.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFBookmarkSetFontStyle(FGSPDFBookmarkRef bookmark, FGSBookmarkFontStyle fontstyle);

/**
 * @brief Set the action actuation of bookmark.
 *
 * @param[in] bookmark	Reference to a bookmark.
 * @param[in] action	Reference to a action.
 * @param[in] document	Reference to a PDF document.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFBookmarkSetAction(FGSPDFBookmarkRef bookmark, FGSPDFActionRef action, FGSPDFDocumentRef document);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFEDIT__
/**@}*/

